Skip to main content

SensorController

The SensorController manages sensor data for SWMM network elements, providing access to real-time and historical sensor readings for nodes and links.

Overview​

This controller handles sensor-related operations including retrieving sensor definitions, time series data, attribute values, and live sensor data. It integrates with multiple Azure storage services to provide comprehensive sensor information for monitoring and analysis.

Data Sources​

  • Azure Table Storage:
    • SensorsXRef table for sensor cross-references
    • SensorData table for sensor time series data
    • AttributeXRef table for attribute definitions
    • Runs table for run metadata
  • Azure Blob Storage:
    • networkmodel container for node/link definitions
  • Configuration: appsettings.json for connection string

Endpoints​

GET /api/sensor/modelsensors​

Retrieves all model sensors with their cross-references to nodes and links.

Response:

  • 200 OK: Returns JSON string containing sensor definitions
  • 500 Internal Server Error: Storage or processing error

Data Flow:

Sensor Data Structure:

{
  "nodeSensors": {
    "sensorId": {
      "nodeIndex": "0",
      "latitude": "41.8781",
      "longitude": "-87.6298",
      "type": "JUNCTION"
    }
  },
  "linkSensors": {
    "sensorId": {
      "linkIndex": "0",
      "fromNode": "node1",
      "toNode": "node2",
      "type": "CONDUIT"
    }
  }
}

GET /api/sensor/sensors​

Retrieves all sensors with their basic information.

Response:

  • 200 OK: Returns JSON string containing sensor list
  • 500 Internal Server Error: Storage or processing error

Data Flow:

GET /api/sensor/nodevalues​

Retrieves a single sensor value for a node at a specific time.

Query Parameters:

  • sensorId (string): Sensor identifier
  • measurement (string): Measurement type
  • reportingDateTime (string): Reporting datetime
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns sensor value as double
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

Data Flow:

GET /api/sensor/linkvalues​

Retrieves a single sensor value for a link at a specific time.

Query Parameters:

  • sensorId (string): Sensor identifier
  • measurement (string): Measurement type
  • reportingDateTime (string): Reporting datetime
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns sensor value as double
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

GET /api/sensor/linktimeseries​

Retrieves time series data for a link sensor.

Query Parameters:

  • sensorId (string): Sensor identifier
  • measurement (string): Measurement type
  • startTime (string): Start time
  • endTime (string): End time
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns time series as JSON string
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

Data Flow:

GET /api/sensor/nodetimeseries​

Retrieves time series data for a node sensor.

Query Parameters:

  • sensorId (string): Sensor identifier
  • measurement (string): Measurement type
  • startTime (string): Start time
  • endTime (string): End time
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns time series as JSON string
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

GET /api/sensor/nodeattributes​

Retrieves attribute values for a node sensor.

Query Parameters:

  • sensorId (string): Sensor identifier
  • reportingDateTimeStringUriEncoded (string): Reporting datetime (URL encoded)
  • reportingTimeStepString (string): Reporting time step

Response:

  • 200 OK: Returns array of attribute values
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

GET /api/sensor/linkattributes​

Retrieves attribute values for a link sensor.

Query Parameters:

  • sensorId (string): Sensor identifier
  • reportingDateTimeStringUriEncoded (string): Reporting datetime (URL encoded)
  • reportingTimeStepString (string): Reporting time step

Response:

  • 200 OK: Returns array of attribute values
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

GET /api/sensor/attributes​

Retrieves sensor attributes as a stream.

Query Parameters:

  • sensorId (string): Sensor identifier
  • reportingDateTimeStringUriEncoded (string): Reporting datetime (URL encoded)
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns attribute stream
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

GET /api/sensor/stagetimeseries​

Retrieves live sensor time series data.

Query Parameters:

  • sensorId (string): Sensor identifier
  • measurement (string): Measurement type
  • startTime (string): Start time
  • endTime (string): End time
  • reportingTimeStep (string): Reporting time step

Response:

  • 200 OK: Returns live time series data
  • 404 Not Found: Sensor or data not found
  • 500 Internal Server Error: Processing error

Data Flow:

Azure Storage Details​

Table Storage Schema​

SensorsXRef Table:

  • PartitionKey: NodeXRef or LinkXRef
  • RowKey: Sensor identifier
  • Value: JSON string with sensor mapping

SensorData Table:

  • PartitionKey: {sensorId}_{date}
  • RowKey: {time}
  • Properties: Measurement values, timestamps

AttributeXRef Table:

  • PartitionKey: Entity type (Node/Link)
  • RowKey: Data type
  • Properties: Attribute definitions, conversion factors

Blob Storage​

  • networkmodel: Contains node and link definitions for sensor mapping

Data Models​

Sensor Entity​

public class SensorsXRefEntity : ITableEntity
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string Value { get; set; }
    public DateTimeOffset Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Attribute Reference​

public class AttributeXRefEntity : ITableEntity
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string EntityType { get; set; }
    public string DataType { get; set; }
    public double ConversionFactor { get; set; }
    public string Units { get; set; }
}

Configuration​

Required Settings:

{
  "Values": {
    "CloudStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
  }
}

Error Handling​

  • Storage Errors: Logged to Azure Table Storage
  • Missing Data: Returns null or empty arrays
  • Invalid Parameters: Graceful parameter validation
  • Time Processing: Handles timezone and format issues
  • Sensor Mapping: Handles missing sensor references

Performance Considerations​

  • Memory Management: Uses memory streams for blob operations
  • Data Parsing: Efficient string parsing for large datasets
  • Time Series Processing: Optimized for large time series
  • Caching: No built-in caching (consider for frequently accessed data)
  • Batch Operations: Efficient sensor data retrieval

Dependencies​

  • Azure.Storage.Blobs
  • Azure.Data.Tables
  • GqcStorage1 (Storage utilities)
  • SwmmModels (Data models)
  • System.Text.Json

Common Sensor Types​

Node Sensors​

  • Depth: Water depth at node
  • Head: Hydraulic head
  • Inflow: Total inflow
  • Overflow: Overflow volume
  • Quality: Water quality parameters
  • Flow: Flow rate
  • Depth: Water depth
  • Velocity: Flow velocity
  • Capacity: Conduit capacity
  • Quality: Water quality parameters

Time Series Processing​

  • Time Indexing: Calculates array indices from timestamps
  • Data Conversion: Applies conversion factors from attribute references
  • Time Windows: Supports start/end time filtering
  • Reporting Steps: Handles different time step intervals
  • Live Data: Real-time sensor data processing

Usage Examples​

Get All Model Sensors:

GET /api/sensor/modelsensors

Get Node Sensor Value:

GET /api/sensor/nodevalues?sensorId=SENSOR001&measurement=depth&reportingDateTime=2023-11-16T12:00:00-05:00&reportingTimeStep=15

Get Link Time Series:

GET /api/sensor/linktimeseries?sensorId=SENSOR002&measurement=flow&startTime=2023-11-16T00:00:00-05:00&endTime=2023-11-16T23:59:59-05:00&reportingTimeStep=15

Get Live Sensor Data:

GET /api/sensor/stagetimeseries?sensorId=SENSOR003&measurement=stage&startTime=2023-11-16T00:00:00-05:00&endTime=2023-11-16T23:59:59-05:00&reportingTimeStep=15

Sensor Data Quality​

  • Data Validation: Checks for valid sensor references
  • Time Alignment: Ensures proper time step alignment
  • Missing Data: Handles gaps in time series
  • Unit Conversion: Applies proper unit conversions
  • Data Integrity: Validates sensor data consistency